Intro

cs_script is a JavaScript based scripting system for Counter-Strike maps.

It is a virtual machine for scripting which exposes various Source2 engine functionality and Counter-Strike specific info such as listening to events, accessing player data, firing I/O events, getting data about gamemodes, etc.

info

script_zoo.vmap is a Valve made map to demonstrate basic functionality of the system, it can be found in Counter-Strike Global Offensive\content\csgo\maps\editor\zoo\script_zoo.vmap

A significant amount of documentation on this page is taken from Counter-Strike Global Offensive\content\csgo\maps\editor\zoo\point_script.d.ts

BUG

Currently when working on your script, when you load your map the script will fail to execute, to fix it you need to save the script file in your text editor which will cause the script to be recompiled and start working.

This bug does not affect your map once it has been publiched on the workshop, it will work as expected there.

Counter-Strike Global Offensive\content\csgo\maps\editor\zoo\point_script.d.ts documents the JavaScript API for cs_script scripts attached to point_script entities. This file is a TypeScript Declaration file.

This file can be used by various editors to provide tooling while editing JavaScript. Next to this file is a tsconfig.json file configured for editing JavaScript targetting the current version used by CS2.

Place copies of these two files, point_script.d.ts and tsconfig.json, next to your scripts and some editors will begin providing tooling without further configuration. These two files will be maintained as the cs_script API changes or the JavaScript version in CS2 is updated.

"cs_script/point_script" is the module provided to scripts loaded for point_script entities.

note

The are projects offering full TypeScript wrappers over the current JavaScript API, such as cs_script_boilerplate however this page will not focus on that.

Setup

• Create a JavaScript file (.js) that imports this module.
  • See hello.js for an example.
• Create a point_script entity in your map and set its cs_script field to reference your JavaScript file as a vjs asset.
  • See Counter-Strike Global Offensive\content\csgo\maps\editor\zoo\script_zoo.vmap. There is a point_script entity in there named "hello_cs_script" that runs hello.js. There are a handful of other examples as well.

Execution

• The compiled version of your script (.vjs_c) will be loaded during map load.
• When the point_script entity is spawned it will execute all code at the top level scope of your script.
• Register callbacks on Instance to setup code that executes at various times throughout the lifetime of the map.
  • A function passed to Instance.OnActivate will be invoked when the point_script entity is activated.
  • A function passed to Instance.OnPlayerJump will be invoked when any player in the map jumps.

Tips

• Entity variables are stable. Two variables referring to the same entity will be reference equals (===).
• Extra values attached to an entity variable will still be there if the variable is fetched again.
• A map can have multiple point_script entities. Each script will run with its own Instance, set of globals, and set of entity variables.

Tools Mode

• In tools mode, saving changes to your script will recompile your file, clear all registered callbacks, and re-run the top level scope of your script.
• Global variables and instances of entity variables will persist across reloads.
  • Beware. This is an avenue for holding references to code from previous iterations of your script. This is only a concern in tools mode.
• See Instance.OnScriptReload for a tool to handle edge cases around reloading.